Status & Error Codes
Overview
The Stingray Music API is designed to provide clear and actionable feedback when an error occurs during an API request. Each error response includes a set of parameters that help identify the issue and facilitate troubleshooting. Understanding these error responses is crucial for developers to handle exceptions gracefully and provide a smooth user experience.
Error Response Structure
When the API encounters an error, it returns a response with the following parameters:
- code: A unique error code that identifies the type of error.
- message: A brief description of the error.
- details: Additional information about the error, which may include steps for resolution or clarification.
- trace id (optional): A UUID included with certain types of errors (often with HTTP 500 errors) to trace the error between the client side and Stingray side.
Example
{
"code": "404000",
"message": "A message about the error.",
"details": "Additional details on the error.",
"trace_id": "5951b3dc-5702-418a-a7dd-a8f90141ad4d"
}
Error Codes and Messages
The API uses specific error codes and messages to indicate different types of errors. Below is a list of the API error codes, along with their associated messages:
Client Errors (4xx)
| Code | Message |
|---|---|
| 400001 | Invalid ip address |
| 400002 | Invalid parameter |
| 401001 | Invalid authorization token |
| 403001 | Access is forbidden |
| 403002 | Resource access is forbidden |
| 404000 | Not found |
Server Errors (5xx)
| Code | Message |
|---|---|
| 500001 | Internal server error |
| 503001 | Server at capacity |
Handling Errors
Developers should implement error handling in their applications to interpret these codes and messages and take appropriate actions, such as:
- Retrying the request when encountering temporary server issues.
- Re-authenticate if the authorization token is invalid.
- Logging the trace id for internal server errors to assist with troubleshooting with Stingray support.
Conclusion
Properly handling errors is essential for maintaining a reliable application that uses the Stingray Music API. By utilizing the provided error codes and messages, developers can ensure that their applications respond appropriately to various error conditions and provide guidance to users on how to proceed when an error is encountered.